ERROR_READ_ONLY
ERROR_READ_ONLY = 1
Abstract skeleton of an address book/repository
$primary_key : string
$groups : bool
$export_groups : bool
$readonly : bool
$searchonly : bool
$undelete : bool
$ready : bool
$group_id : null|string|int
$list_page : int
$page_size : int
$sort_col : string
$sort_order : string
$date_cols : string[]
$coltypes : array
$vcard_map : string[]
$error : ?array
set_search_set(mixed $filter) : void
Sets a search filter.
This affects the contact set considered when using the count() and list_records() operations to those contacts that match the filter conditions. If no search filter is set, all contacts in the addressbook are considered.
This filter mechanism is applied in addition to other filter mechanisms, see the description of the count() operation.
mixed | $filter | Search params to use in listing method, obtained by get_search_set() |
list_records(?array $cols = null, int $subset, bool $nocount = false) : \rcube_result_set
Lists the current set of contact records.
See the description of count() for the criteria determining which contacts are considered for the listing.
The actual records returned may be fewer, as only the records for the current page are returned. The returned records may be further limited by the $subset parameter, which means that only the first or last $subset records of the page are returned, depending on whether $subset is positive or negative. If $subset is 0, all records of the page are returned. The returned records are found in the $records property of the returned result set.
Finally, the $first property of the returned result set contains the index into the total set of filtered records (i.e. not considering the segmentation into pages) of the first returned record before applying the $subset parameter (i.e., $first is always a multiple of the page size).
The $nocount parameter is an optimization that allows to skip querying the total amount of records of the filtered set if the caller is only interested in the records. In this case, the $count property of the returned result set will simply contain the number of returned records, but the filtered set may contain more records than this.
The result of the operation is internally cached for later retrieval using get_result().
?array | $cols | List of columns to include in the returned records (null means all) |
int | $subset | Only return this number of records of the current page, use negative values for tail |
bool | $nocount | True to skip the count query (select only) |
Indexed list of contact records, each a hash array
search(string|string[] $fields, string|string[] $value, int $mode, bool $select = true, bool $nocount = false, string|string[] $required = []) : \rcube_result_set
Search records
Depending on the given parameters the search() function operates in different ways (in the order listed):
"Direct ID search" - when $fields is either 'ID' or $this->primary_key - $values is either a string of contact IDs separated by self::SEPARATOR (,) or an array of contact IDs - Any contact with one of the given IDs is returned
"Advanced search" - when $value is an array - Each value in $values is the search value for the field in $fields at the same index - All fields must match their value to be included in the result ("AND" semantics)
"Search all fields" - when $fields is '*' (note: $value is a single string) - Any field must match the value to be included in the result ("OR" semantics)
"Search given fields" - if none of the above matches - Any of the given fields must match the value to be included in the result ("OR" semantics)
All matching is done case insensitive.
The search settings are remembered (see set_search_set()) until reset using the reset() function. They can be retrieved using get_search_set(). The remembered search settings must be considered by list_records() and count().
The search mode can be set by the admin via the config.inc.php setting addressbook_search_mode. It is used as a bit mask, but the search modes are exclusive (SEARCH_GROUPS is combined with one of other modes): SEARCH_ALL: substring search (abc) SEARCH_STRICT: Exact match search (case insensitive =) SEARCH_PREFIX: Prefix search (abc*) SEARCH_GROUPS: include groups in search results (if supported)
When records are requested in the returned rcube_result_set ($select is true), the results will only include the contacts of the current page (see list_page, page_size). The behavior is as described with the list_records function, and search() can be thought of as a sequence of set_search_set() and list_records() under that filter.
If $nocount is true, the count property of the returned rcube_result_set will contain the amount of records contained within that set. Calling search() with $select=false and $nocount=true is not a meaningful use case and will result in an empty result set without records and a count property of 0, which gives no indication on the actual record set matching the given filter.
The result of the operation is internally cached for later retrieval using get_result().
string|string[] | $fields | Field names to search in |
string|string[] | $value | Search value, or array of values, one for each field in $fields |
int | $mode | Search mode. Sum of rcube_addressbook::SEARCH_*. |
bool | $select | True if records are requested in the result, false if count only |
bool | $nocount | True to skip the count query (select only) |
string|string[] | $required | Field or list of fields that cannot be empty |
Contact records and 'count' value
count() : \rcube_result_set
Count the number of contacts in the database matching the current filter criteria.
The current filter criteria are defined by the search filter (see search()/set_search_set()) and the currently active group (see set_group()), if applicable.
Result set with values for 'count' and 'first'
get_record(mixed $id, bool $assoc = false) : \rcube_result_set|array
Get a specific contact record
mixed | $id | Record identifier(s) |
bool | $assoc | True to return record as associative array, otherwise a result set is returned |
Result object with all record fields
validate(array $save_data, bool $autofix = false) : bool
Check the given data before saving.
If input isn't valid, the message to display can be fetched using get_error()
array | $save_data | Associative array with data to save |
bool | $autofix | Attempt to fix/complete record automatically |
True if input is valid, False if not.
insert(array $save_data, bool $check = false) : mixed
Create a new contact record
array | $save_data | Associative array with save data Keys: Field name with optional section in the form FIELD:SECTION Values: Field value. Can be either a string or an array of strings for multiple values |
bool | $check | True to check for duplicates first |
The created record ID on success, False on error
update(mixed $id, array $save_cols) : mixed
Update a specific contact record
mixed | $id | Record identifier |
array | $save_cols | Associative array with save data Keys: Field name with optional section in the form FIELD:SECTION Values: Field value. Can be either a string or an array of strings for multiple values |
On success if ID has been changed returns ID, otherwise True, False on error
set_group(mixed $group_id) : mixed
Sets/clears the current group.
This affects the contact set considered when using the count(), list_records() and search() operations to those contacts that belong to the given group. If no current group is set, all contacts in the addressbook are considered.
This filter mechanism is applied in addition to other filter mechanisms, see the description of the count() operation.
mixed | $group_id |
rename_group(string $group_id, string $newname, string $newid) : string|false
Rename a specific contact group
string | $group_id | Group identifier |
string | $newname | New name to set for this group |
string | $newid | New group identifier (if changed, otherwise don't set) |
New name on success, false if no data was changed
get_record_groups(mixed $id) : array
Get group assignments of a specific contact record
mixed | $id | Record identifier |
List of assigned groups indexed by a group ID. Every array element can be just a group name (string), or an array with 'ID' and 'name' elements.
get_col_values(string $col, array $data, bool $flat = false) : array
Utility function to return all values of a certain data column either as flat list or grouped by subtype
string | $col | Col name |
array | $data | Record data array as used for saving |
bool | $flat | True to return one array with all values, False for hash array with values grouped by type |
List of column values
compose_display_name(array $contact, bool $full_email = false) : string
Compose a valid display name from the given structured contact data
array | $contact | Hash array with contact data as key-value pairs |
bool | $full_email | Don't attempt to extract components from the email address |
Display name
compose_list_name(array $contact) : string
Compose the name to display in the contacts list for the given contact record.
This respects the settings parameter how to list contacts.
array | $contact | Hash array with contact data as key-value pairs |
List name
compose_search_name(array $contact, string $email = null, string $name = null, string $templ = null) : string
Build contact display name for autocomplete listing
array | $contact | Hash array with contact data as key-value pairs |
string | Optional email address |
|
string | $name | Optional name (self::compose_list_name() result) |
string | $templ | Optional template to use (defaults to the 'contact_search_name' config option) |
Display name
compare_search_value(string $colname, string|array $value, string $search, int $mode) : bool
Compare search value with contact data
string | $colname | Data name |
string|array | $value | Data value |
string | $search | Search value |
int | $mode | Search mode |
Comparison result